Sprite 1984

home *** CD-ROM | disk | FTP | other *** search

/ Sprite 1984 - 1993 / Sprite 1984 - 1993.iso / man / files.fmt / man.man < prev next >

Wrap

Text File | 1989-05-28 | 13.1 KB | 333 lines

man File Formats man _________________________________________________________________ NNAAMMEE man - Ditroff macros for writing manual entries _________________________________________________________________ IINNTTRROODDUUCCTTIIOONN Manual entries in Sprite are formatted with the ddiittrrooffff pro- gram using the --mmaann macros. This manual entry summarizes the features provided by the --mmaann macros. For more general information on how to write manual entries for Sprite, refer to _T_h_e _S_p_r_i_t_e _E_n_g_i_n_e_e_r_i_n_g _M_a_n_u_a_l. Templates of manual entries for programs and library procedures are available in //sspprriittee//lliibb//ffoorrmmss//ccmmdd..mmaann and //sspprriittee//lliibb//ffoorrmmss//lliibb..mmaann respectively. MMAACCRROOSS The --mmaann macros are: ..AAPP _t_y_p_e _n_a_m_e _i_n_O_u_t [_i_n_d_e_n_t] Argument paragraph. The _t_y_p_e, _n_a_m_e, and _i_n_O_u_t argu- ments give information about this argument: its type, its name, and a string indicating how the argument is used. _I_n_O_u_t must be either iinn (meaning the argument is used by the procedure but is not used to modify infor- mation in the caller's memory), oouutt (meaning the argu- ment points to information in the caller's memory which the procedure modifies without ever reading), or iinn//oouutt (meaning the argument points to information in the caller's memory which is both read and written by the procedure). Text following the ..AAPP line provides a short description of the argument: it will be indented to appear to the right of _t_y_p_e, _n_a_m_e, and _i_n_O_u_t. If _i_n_d_e_n_t is specified, it determines the indentation of the following text in ens; however, this argument is normally omitted, in which case a reasonable default is picked. In a sequence of argument descriptions, each with its own ..AAPP call, the _t_y_p_e, _n_a_m_e, _i_n_O_u_t, and description parts will be lined up in columns. The ..AASS macro may be used to size the columns. ..AASS _t_y_p_e _n_a_m_e Set argument sizes for ..AAPP. _T_y_p_e and _n_a_m_e specify the largest such arguments that will be used in a following series of ..AAPP calls; tab stops are set for the follow- ing calls so that the _t_y_p_e and _n_a_m_e columns will line up with adequate spacing. If this macro is never invoked, then default field widths will be chosen, which are valid for small arguments. ..BB [_a_r_g_s] Sprite v.1.0 February 17, 1989 1 man File Formats man Print in boldface. If any _a_r_g_s are given, then all of the arguments are printed in boldface (up to six of them). Otherwise, everything on the next line of input is printed in boldface. In either case, the font reverts to roman after the arguments or following line have been printed. ..BBEE End boxed text. Close off a box started previously with ..BBSS. ..BBSS Start boxed text. Everything up to the matching ..BBEE macro will be enclosed in a box. This is used for the summary boxes at the tops of manual entries. ..DDEE End a display: cancel the effects of the previous ..DDSS macro, returning to normal indentation and fill mode. ..DDSS Start a display. All lines up until the next ..DDEE macro will be indented and output in no-fill mode. ..DDTT Reset tabs to default spacings (every half-inch). ..IIPP _t_a_g [_i_n_d_e_n_t] This is identical to ..IIPP in the --mmss macros. It starts an indented paragraph with ttaagg (if given) as an out- dented tag. If _i_n_d_e_n_t is given, it specifies how much the paragraph will be indented, in ens. ..HHPP Start a paragraph with a hanging indent (the first line will be outdented relative to the rest of the para- graph). ..HHSS _s_e_c_t_i_o_n [_d_a_t_e [_v_e_r_s_i_o_n]] Header for Sprite. This macro should be used in place of ..TTHH for all Sprite manual entries. It should be the first thing in the entry's source file. _S_e_c_t_i_o_n indi- cates which section of the manual this entry belongs to, and should be one of: aaddmmiinn The manual entry describes an administra- tive program (i.e. one whose binary is under //sspprriittee//aaddmmiinn). Administrative pro- grams are not used by normal users. ccmmddss The manual entry describes a user-level application program. This section is equivalent to section 1 of UNIX manuals. ddaaeemmoonnss The manual entry describes a daemon pro- gram. Daemons are programs that run in background to provide various system ser- vices, such as iinneettdd or llppdd. They are Sprite v.1.0 February 17, 1989 2 man File Formats man normally invoked automatically at boot-time or when needed, and aren't usually visible to ordinary users. ddeevv The manual entry describes the characteris- tics of a particular type of I/O device or pseudo-device, along with the I/O controls that may be applied to devices of that type. This section is equivalent to sec- tion 4 of UNIX manuals. ffiilleess The manual entry describes the format of a particular file or file type. For example, the manual entry you are reading is in the ffiilleess section. This section is equivalent to section 5 of UNIX manuals. lliibb The manual entry describes one or more pro- cedures in one of the standard C libraries. This section is equivalent to the combina- tion of sections 2 and 3 of UNIX manuals. ttccll The manual entry describes one or more pro- cedures from the Tcl command language library. The _d_a_t_e argument to ..HHSS is optional and specifies the date on which the entry (or its corresponding program) was last modified. The _v_e_r_s_i_o_n argument is optional and specifies the Sprite version number corresponding to this version of the manual entry. The current default is ``1.0''. ..II [_a_r_g_s] Print in italics. If any _a_r_g_s are given, then all of the arguments are printed in italics (up to six of them). Otherwise, everything on the next line of input is printed in italics. In either case, the font reverts to roman after the arguments or following line have been printed. ..LLGG [_a_r_g_s] Print in a larger font. If any _a_r_g_s are given, then all of the arguments are printed in a larger font (up to six of them). Otherwise, everything on the next line of input is printed in a larger font. In either case, the font reverts to normal size after the argu- ments or following line have been printed. ..LLPP Start a new paragraph. Same as ..PPPP. ..PPDD _d_i_s_t_a_n_c_e Sprite v.1.0 February 17, 1989 3 man File Formats man Set the spacing between paragraphs to _d_i_s_t_a_n_c_e. ..PPPP Start a new paragraph. ..RREE [_l_e_v_e_l] End right-shifted text, moving the indentation level back to its previous level. Normally, each ..RRSS moves the indentation back one level (in the case of nested ..RRSS calls). However, if _l_e_v_e_l is specified, it gives the index of the nesting level from which to return. For example, ..RRSS 33 says to return from 3 levels of nesting to 2 levels (when this call is invoked, there better be at least three nested ..RRSS calls in effect). ..RRSS 00 says to return from all nested ..RRSS calls. ..RRSS [_i_n_d_e_n_t] Right shift. From now on, indent all future text (up to the matching ..RREE) by an additional amount equal to _i_n_d_e_n_t ens. If _i_n_d_e_n_t isn't specified, then use the current indentation (from the last ..TTPP or ..IIPP) as the amount of additional indentation. Pairs of ..RRSS and ..RREE calls may be nested. The ..SSHH macro cancels all active ..RRSS calls. ..SSHH _n_a_m_e [_m_o_r_e_N_a_m_e ...] Start a new section named _n_a_m_e. The _n_a_m_e may actually consist of up to six distinct arguments. ..SSSS _n_a_m_e [_m_o_r_e_N_a_m_e ... ] Start a new subsection named _n_a_m_e. The _n_a_m_e may actu- ally consist of up to six distinct arguments. ..SSMM [_a_r_g_s] Print in a smaller font. If any _a_r_g_s are given, then all of the arguments are printed in a smaller font (up to six of them). Otherwise, everything on the next line of input is printed in a smaller font. In either case, the font reverts to normal size after the argu- ments or following line have been printed. ..TTHH _n_a_m_e _s_e_c_t_i_o_n [_d_a_t_e [_v_e_r_s_i_o_n]] Set title and heading. This macro is obsolete. It is used for old UNIX manual pages only. For Sprite man pages, the ..HHSS macro should be used instead. _N_a_m_e gives the name of the manual page, which will appear in the upper-right and upper-left corners of each page. _S_e_c_t_i_o_n gives the section number. _D_a_t_e gives the last-modified-time for the program; if not specified, it defaults to blank. _V_e_r_s_i_o_n gives the operating sys- tem version that this manual entry corresponds to. The default for _v_e_r_s_i_o_n varies in time; see the ttmmaacc..aann source file for the current value. Sprite v.1.0 February 17, 1989 4 man File Formats man ..TTPP [_i_n_d_e_n_t] Start a tagged paragraph. The following line contains a tag, and everything after that contains the contents of the paragraph. The tag will be printed outdented to the normal left margin, and the paragraph will be indented relative to the tag. If _i_n_d_e_n_t is specified, then the indent distance is changed to _i_n_d_e_n_t ens (the indent distance is sticky across calls to ..TTPP and ..IIPP but gets reset to a default value by ..PPPP and ..SSHH). For example, each of the macro descriptions in this partic- ular manual entry was formatted using the ..TTPP macro. ..VVEE End vertical sidebar. Starting with the output line following the current one, do not print vertical side- bars. ..VVSS Start vertical sidebar. From now on, starting with the current output line, a vertical bar will appear at the right side of all output lines. This will continue until the next ..VVEE call. Sidebars should be used to indicate recent changes in the manual entry. KKEEYYWWOORRDDSS ditroff, format, macros, -man, manual entry Sprite v.1.0 February 17, 1989 5